SQL Agent

An SQL Agent combines the reasoning capabilities of LLMs with structured database access. Instead of writing SQL manually, users ask questions in natural language and the agent autonomously discovers the schema, constructs queries, and returns answers.

Why SQL Agents Matter

Traditional database access requires SQL knowledge. An SQL Agent bridges this gap:

graph LR
    subgraph Traditional
        A[User] --> B[Write SQL]
        B --> C[Execute Query]
        C --> D[Interpret Results]
    end
    subgraph SQL Agent
        E[User Question] --> F[Agent Reasons]
        F --> G[Auto-generates SQL]
        G --> H[Natural Language Answer]
    end

SQL Agents provide:

Natural Language Interface: Ask questions without knowing SQL
Schema Discovery: Agent explores database structure automatically
Query Generation: Constructs correct SQL based on user intent
Safe Execution: Read-only queries prevent accidental modifications

Architecture

synalinks.SQLAgent wires a FunctionCallingAgent with three pre-built tools bound to a KnowledgeBase:

flowchart TD
    A[User Question] --> B[SQLAgent]
    B --> C{Select Tool}
    C -->|Discover structure| D[get_database_schema]
    C -->|View sample data| E[get_table_sample]
    C -->|Execute query| F[run_sql_query]
    D --> G[Schema Info]
    E --> H[Sample Rows]
    F --> I[Query Results]
    G --> B
    H --> B
    I --> B
    B --> J[Natural Language Answer + SQL]

The agent follows an autonomous loop: it first discovers the schema (or reads the tables from the system instructions), optionally samples data to understand the format, then constructs and executes SQL queries until it has enough information to answer.

Available Tools

Tool	Description
`get_database_schema`	Returns all tables and their columns with types
`get_table_sample`	Fetches sample rows with `LIMIT`/`OFFSET` pagination
`run_sql_query`	Executes read-only `SELECT` queries

Result sets are rendered as CSV by default so the LM spends fewer input tokens reading tabular data. Set output_format="json" on the SQLAgent if you want list-of-dicts instead.

Defining Input and Output Models

import synalinks

class Query(synalinks.DataModel):
    """A natural language query about the database."""
    query: str = synalinks.Field(
        description="The user's question about the data in natural language"
    )

class SQLResult(synalinks.DataModel):
    """The result of the SQL agent's analysis."""
    answer: str = synalinks.Field(
        description="A clear, natural language answer to the user's question"
    )
    sql_query: str = synalinks.Field(
        description="The SQL query that was executed to get the answer"
    )

The Query model captures the user's natural language question. The SQLResult model structures the output to include both a human-readable answer and the SQL used, providing transparency into the agent's reasoning.

Building the Agent

SQLAgent takes a KnowledgeBase + LanguageModel + output data model and handles tool wiring internally — no manual Tool definitions needed.

# Create Knowledge Base with your data models
kb = synalinks.KnowledgeBase(
    uri="duckdb://my_database.db",
    data_models=[Customer, Product, SalesOrder],
)

# Configure language model
lm = synalinks.LanguageModel(model="gemini/gemini-3.1-flash-lite-preview")

# Build the agent via the Functional API
inputs = synalinks.Input(data_model=Query)
outputs = await synalinks.SQLAgent(
    knowledge_base=kb,
    language_model=lm,
    data_model=SQLResult,
    max_iterations=10,
)(inputs)

sql_agent = synalinks.Program(
    inputs=inputs,
    outputs=outputs,
    name="sql_agent",
)

Safety Considerations

Safety is the Knowledge Base's responsibility, not the agent's. The DuckDB adapter treats read_only=True (which run_sql_query passes by default) as the whole safety contract, enforced at two layers — both using DuckDB's own machinery, so there are no hand-rolled keyword blocklists (which leak false negatives via comments, string literals, casing, or stacked statements like SELECT 1; DROP TABLE x):

Parser check (blocks writes). Each statement is parsed with DuckDB's own parser and rejected unless it's a SELECT. This catches multi-statement injection, COPY (SELECT ...) TO 'file' exfiltration, ATTACH, EXPORT, and every other side-effecting statement.
Sandbox (blocks external I/O). The persistent connection has enable_external_access=false applied at construction time, so SELECT table functions that touch the host filesystem or network — read_csv, read_parquet, read_json, read_blob, read_text, glob, the httpfs/S3 variants — return a permission error.

Example Usage

# Ask a natural language question
result = await sql_agent(Query(query="Who are the top 3 customers by orders?"))

print(result["answer"])
# Output: "The top 3 customers are: Carlos Garcia ($1539.96),
#          Alice Johnson ($1489.96), and Diana Chen ($379.94)"

print(result["sql_query"])
# Output: "SELECT c.name, SUM(o.total_amount) as total
#          FROM Customer c JOIN SalesOrder o ON c.id = o.customer_id
#          GROUP BY c.name ORDER BY total DESC LIMIT 3"

The agent automatically: 1. Discovered the Customer and SalesOrder tables 2. Understood the relationship via customer_id 3. Wrote a proper JOIN with aggregation 4. Returned both the answer and the SQL for transparency

Key Takeaways

One module, three tools: synalinks.SQLAgent bundles schema discovery, table sampling, and read-only SQL execution into a single ready-to-use module. No manual tool wiring.
Token-efficient by default: output_format="csv" minimizes LM input tokens on wide result sets. Switch to "json" only if downstream code needs typed structured data.
Pagination: get_table_sample accepts limit / offset; for arbitrary queries the LM is instructed to include LIMIT clauses.
Safety First: The run_sql_query tool always passes read_only=True to kb.sql(...). Non-SELECT statements are rejected at the parser; the sandbox blocks read_csv / httpfs.
Transparent Outputs: Include the generated SQL in the output schema so users can verify and learn from the agent's reasoning.